Node / ReticulumProjects / Reticulum.git / files / docs / source / gettingstartedfast.rst

Displaying Raw • Download

Tc9d1d9********************

Tc9d1d9Getting Started Fast

Tc9d1d9********************

The best way to get started with the Reticulum Network Stack depends on what you want to do. This guide will outline sensible starting paths for different scenarios.

Tc9d1d9Standalone Reticulum Installation

Tc9d1d9=================================

If you simply want to install Reticulum and related utilities on a system, the easiest way is via the Ta5d6ff``Ta5d6ffpipTa5d6ff`` package manager:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

pip install rns

If you do not already have pip installed, you can install it using the package manager of your system with a command like Ta5d6ff``Ta5d6ffsudo apt install python3-pipTa5d6ff``, Ta5d6ff``Ta5d6ffsudo pamac install python-pipTa5d6ff`` or similar.

You can also dowload the Reticulum release wheels from GitHub, or other release channels, and install them offline using Ta5d6ff``Ta5d6ffpipTa5d6ff``:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

pip install ./rns-1.1.2-py3-none-any.whl

On platforms that limit user package installation via Ta5d6ff``Ta5d6ffpipTa5d6ff``, you may need to manually allow this using the Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` command line flag when installing. This will not actually break any packages, unless you have installed Reticulum directly via your operating system's package manager.

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

pip install rns --break-system-packages

For more detailed installation instructions, please see the Te6edf3:ref:Te6edf3`Platform-Specific Install Notes<install-guides>` section.

After installation is complete, it might be helpful to refer to the Te6edf3:ref:Te6edf3`Using Reticulum on Your System<using-main>` chapter.

Tc9d1d9Resolving Dependency & Installation Issues

Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

On some platforms, there may not be binary packages available for all dependencies, and Ta5d6ff``Ta5d6ffpipTa5d6ff`` installation may fail with an error message. In these cases, the issue can usually be resolved by installing the development essentials packages for your platform:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# Debian / Ubuntu / Derivatives

sudo apt install build-essential

T8b949e# Arch / Manjaro / Derivatives

sudo pamac install base-devel

T8b949e# Fedora

sudo dnf groupinstall Ta5d6ff"Development Tools" Ta5d6ff"Development Libraries"

With the base development packages installed, Ta5d6ff``Ta5d6ffpipTa5d6ff`` should be able to compile any missing dependencies from source, and complete installation even on platforms that don't have pre-compiled packages available.

Tc9d1d9Try Using a Reticulum-based Program

Tc9d1d9===================================

If you simply want to try using a program built with Reticulum, a Te6edf3:ref:Te6edf3`range of different programs <software-main>` exist that allow basic communication and a various other useful functions, even over extremely low-bandwidth Reticulum networks.

Tc9d1d9Using the Included Utilities

Tc9d1d9============================

Reticulum comes with a range of included utilities that make it easier to manage your network, check connectivity and make Reticulum available to other programs on your system.

You can use Ta5d6ff``Ta5d6ffrnsdTa5d6ff`` to run Reticulum as a background or foreground service, and the Ta5d6ff``Ta5d6ffrnstatusTa5d6ff``, Ta5d6ff``Ta5d6ffrnpathTa5d6ff`` and Ta5d6ff``Ta5d6ffrnprobeTa5d6ff`` utilities to view and query network status and connectivity.

To learn more about these utility programs, have a look at the Te6edf3:ref:Te6edf3`Using Reticulum on Your System<using-main>` chapter of this manual.

Tc9d1d9Creating a Network With Reticulum

Tc9d1d9=================================

To create a network, you will need to specify one or more *interfaces* for Reticulum to use. This is done in the Reticulum configuration file, which by default is located at Ta5d6ff``Ta5d6ff~/.reticulum/configTa5d6ff``. You can get an example configuration file with all options via Ta5d6ff``Ta5d6ffrnsd --exampleconfigTa5d6ff``.

When Reticulum is started for the first time, it will create a default configuration file, with one active interface. This default interface uses your existing Ethernet and WiFi networks (if any), and only allows you to communicate with other Reticulum peers within your local broadcast domains.

To communicate further, you will have to add one or more interfaces. The default configuration includes a number of examples, ranging from using TCP over the internet, to LoRa and Packet Radio interfaces.

With Reticulum, you only need to configure what interfaces you want to communicate over. There is no need to configure address spaces, subnets, routing tables, or other things you might be used to from other network types.

Once Reticulum knows which interfaces it should use, it will automatically discover topography and configure transport of data to any destinations it knows about.

In situations where you already have an established WiFi or Ethernet network, and many devices that want to utilise the same external Reticulum network paths (for example over LoRa), it will often be sufficient to let one system act as a Reticulum gateway, by adding any external interfaces to the configuration of this system, and then enabling transport on it. Any other device on your local WiFi will then be able to connect to this wider Reticulum network just using the default (Te6edf3:ref:Te6edf3`AutoInterface<interfaces-auto>`) configuration.

Possibly, the examples in the config file are enough to get you started. If you want more information, you can read the Te6edf3:ref:Te6edf3`Building Networks<networks-main>` and Te6edf3:ref:Te6edf3`Interfaces<interfaces-main>` chapters of this manual, but most importantly, start with reading the next section, Te6edf3:ref:Te6edf3`Bootstrapping Connectivity<bootstrapping-connectivity>`, as this provides the most essential understanding of how to ensure reliable connectivity with a minimum of maintenance.

Tb4b4b4.. Tff7b72_bootstrapping-connectivity:

Tc9d1d9Bootstrapping Connectivity

Tc9d1d9==========================

Reticulum is not a service you subscribe to, nor is it a single global network you "join". It is a *networking stack*; a toolkit for building communications systems that align with your specific values, requirements, and operational environment. The way you choose to connect to other Reticulum peers is entirely your own choice.

One of the most powerful aspects of Reticulum is that it provides a multitude of tools to establish, maintain, and optimize connectivity. You can use these tools in isolation or combine them in complex configurations to achieve a vast array of goals.

Whether your aim is to create a completely private, air-gapped network for your family; to build a resilient community mesh that survives infrastructure collapse; to connect far and wide to as many nodes as possible; or simply to maintain a reliable, encrypted link to a specific organization you care about, Reticulum provides the mechanisms to make it happen.

There is no "right" or "wrong" way to build a Reticulum network, and you don't need to be a network engineer just to get started. If the information flows in the way you intend, and your privacy and security requirements are met, your configuration is a success. Reticulum is designed to make the most challenging and difficult scenarios attainable, even when other networking technologies fail.

Tc9d1d9Finding Your Way

Tc9d1d9^^^^^^^^^^^^^^^^

When you first start using Reticulum, you need a way to obtain connectivity with the peers you want to communicate with - the process of *bootstrapping connectivity*.

Tb4b4b4.. Tff7b72importantTb4b4b4::

A common mistake in modern networking is the reliance on a few centralized, hard-coded entrypoints. If every user simply connects to the same list of public IP addresses found on a website, the network becomes brittle, centralized, and ultimately fails to deliver on the promise of decentralization and resilience. You have a responsibility here.

Reticulum encourages the approach of *organic growth*. Instead of relying on permanent static connections to distant servers, you can use temporary bootstrap connections to continously *discover* more relevant or local infrastructure. Once discovered, your system can automatically form stronger, more direct links to these peers, and discard the temporary bootstrap links. This results in a web of connections that are geographically relevant, resilient and efficient.

It *is* possible to simply add a few public entrypoints to the Ta5d6ff``Ta5d6ff[interfaces]Ta5d6ff`` section of your Reticulum configuration and be connected, but a better option is to enable Te6edf3:ref:Te6edf3`interface discovery<using-interface_discovery>` and either manually select relevant, local interfaces, or enable discovered interface auto-connection.

A relevant option in this context is the Te6edf3:ref:Te6edf3`bootstrap only<interfaces-options>` interface option. This is an automated tool for better distributing connectivity. By enabling interface discovery and auto-connection, and marking an interface as Ta5d6ff``Ta5d6ffbootstrap_onlyTa5d6ff``, you tell Reticulum to use that interface primarliy to find connectivity options, and then disconnect it once sufficient entrypoints have been discovered. This helps create a network topology that favors locality and resilience over the simple centralization caused by using only a few static entrypoints.

Good places to find interface definitions for bootstrapping connectivity are websites like

Ta5d6ff`directory.rns.recipes Tffd700<https://directory.rns.recipes/>Ta5d6ff`_ and Ta5d6ff`rmap.world Tffd700<https://rmap.world/>Ta5d6ff`_.

Tc9d1d9Build Personal Infrastructure

Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You do not need a datacenter to be a meaningful part of the Reticulum ecosystem. In fact, the most important nodes in the network are often the smallest ones.

We strongly encourage everyone, even home users, to think in terms of building **personal infrastructure**. Don't connect every phone, tablet, and computer in your house directly to a public internet gateway. Instead, repurpose an old computer, a Raspberry Pi, or a supported router to act as your own, personal **Transport Node**:

T79c0ff* Your local Transport Node sits in your home, connected to your WiFi and perhaps a radio interface (like an RNode).

T79c0ff* You configure this node with a Ta5d6ff``Ta5d6ffbootstrap_onlyTa5d6ff`` interface (perhaps a TCP tunnel to a wider network) and enable interface discovery.

T79c0ff* While you sleep, work, or cook, your node listens to the network. It discovers other local community members, validates their Network Identities, and automatically establishes direct links.

T79c0ff* Your personal devices now connect to your *local* node, which is integrated into a living, breathing local mesh. Your traffic flows through local paths provided by other real people in the community rather than bouncing off a distant server.

**Don't wait for others to build the networks you want to see**. Every network is important, perhaps even most so those that support individual families and persons. Once enough of this personal, local infrastructure exist, connecting them directly to each other, without traversing the public Internet, becomes inevitable.

Tc9d1d9Mixing Strategies

Tc9d1d9^^^^^^^^^^^^^^^^^

There is no requirement to commit to a single strategy. The most robust setups often mix static, dynamic, and discovered interfaces.

T79c0ff* **Static Interfaces:** You maintain a permanent interface to a trusted friend or organization using a static configuration.

T79c0ff* **Bootstrap Links:** You connect a Ta5d6ff``Ta5d6ffbootstrap_onlyTa5d6ff`` interface to a public gateway on the Internet to scan for new connectable peers or to regain connectivity if your other interfaces fail.

T79c0ff* **Local Wide-Area Connectivity:** You run a Ta5d6ff``Ta5d6ffRNodeInterfaceTa5d6ff`` on a shared frequency, giving you completely self-sovereign and private wide-area access to both your own network and other Reticulum peers globally, without any "service providers" being able to control or monitor how you interact with people.

By combining these methods, you create a system that is secure against single points of failure, adaptable to changing network conditions, and better integrated into your physical and social reality.

Tc9d1d9Network Health & Responsibility

Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

As you participate in the wider networks you discover and build, you will inevitably encounter peers that are misconfigured, malicious, or simply broken. To protect your resources and those of your local peers, you can utilize the Te6edf3:ref:Te6edf3`Blackhole Management<using-blackhole_management>` system.

Whether you manually block a spamming identity or subscribe to a blackhole list maintained by a trusted Network Identity, these tools help ensure that *your* transport capacity is used for what *you* consider legitimate communication. This keeps your local segment efficient and contributes to the health of the wider network.

Tc9d1d9Contributing to the Global Ret

Tc9d1d9^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you have the means to host a stable node with a public IP address, consider becoming a Te6edf3:ref:Te6edf3`Public Entrypoint<hosting-entrypoints>`. By Te6edf3:ref:Te6edf3`publishing your interface as discoverable<interfaces-discoverable>`, you provide a potential connection point for others, helping the network grow and reach new areas.

For guidelines on how to properly configure a public entrypoint, refer to the Te6edf3:ref:Te6edf3`Hosting Public Entrypoints<hosting-entrypoints>` section.

Tc9d1d9Connect to the Distributed Backbone

Tc9d1d9===================================

A global, distributed backbone of Reticulum Transport Nodes is being run by volunteers from around the world. This network constitutes a heterogenous collection of both public and private nodes that form an uncoordinated, voluntary inter-networking backbone that currently provides global transport and internetworking capabilities for Reticulum.

As a good starting point, you can find interface definitions for connecting your own networks to this backbone on websites such as Ta5d6ff`directory.rns.recipes Tffd700<https://directory.rns.recipes/>Ta5d6ff`_ and Ta5d6ff`rmap.world Tffd700<https://rmap.world/>Ta5d6ff`_.

Tb4b4b4.. Tff7b72tipTb4b4b4::

Don't rely on just a single connection to the distributed backbone for everyday use. It is much better to have several redundant connections configured, and enable the interface discovery options, so your nodes can continously discover peering opportunities as the network evolves. Refer to the Te6edf3:ref:Te6edf3`Bootstrapping Connectivity<bootstrapping-connectivity>` section to understand the options.

Tb4b4b4.. Tff7b72_hosting-entrypoints:

Tc9d1d9Hosting Public Entrypoints

Tc9d1d9==========================

If you want to help build a strong global interconnection backbone, you can host a public (or private) entry-point to a Reticulum network over the Internet. This section offers some helpful pointers. Once you have set up your public entrypoint, it is a great idea to Te6edf3:ref:Te6edf3`make it discoverable over Reticulum<interfaces-discoverable>`.

You will need a machine, physical or virtual with a public IP address, that can be reached by other devices on the Internet.

The most efficient and performant way to host a connectable entry-point supporting many users is to use the Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff``. This interface type is fully compatible with the Ta5d6ff``Ta5d6ffTCPClientInterfaceTa5d6ff`` and Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff`` types, but much faster and uses less system resources, allowing your device to handle thousands of connections even on small systems.

It is also important to set your connectable interface to Ta5d6ff``Ta5d6ffgatewayTa5d6ff`` mode, since this will greatly improve network convergence time and path resolution for anyone connecting to your entry-point.

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini

T8b949e# This example demonstrates a backbone interface

T8b949e# configured for acting as a gateway for users to

T8b949e# connect to either a public or private network

Tff7b72[[Public Gateway]]

Te6edf3type Tff7b72= Ta5d6ffBackboneInterface

Te6edf3enabled Tff7b72= Ta5d6ffyes

Te6edf3mode Tff7b72= Ta5d6ffgateway

Te6edf3listen_on Tff7b72= Ta5d6ff0.0.0.0

Te6edf3port Tff7b72= Ta5d6ff4242

T8b949e# On publicly available interfaces, it is

T8b949e# essential to configure sensible announce

T8b949e# rate targets.

Te6edf3announce_rate_target Tff7b72= Ta5d6ff3600

Te6edf3announce_rate_penalty Tff7b72= Ta5d6ff3600

Te6edf3announce_rate_grace Tff7b72= Ta5d6ff6

If instead you want to make a private entry-point from the Internet, you can use the Te6edf3:ref:Te6edf3`IFAC name and passphrase options<interfaces-options>` to secure your interface with a network name and passphrase.

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini

T8b949e# A private entry-point requiring a pre-shared

T8b949e# network name and passphrase to connect to.

Tff7b72[[Private Gateway]]

Te6edf3type Tff7b72= Ta5d6ffBackboneInterface

Te6edf3enabled Tff7b72= Ta5d6ffyes

Te6edf3mode Tff7b72= Ta5d6ffgateway

Te6edf3listen_on Tff7b72= Ta5d6ff0.0.0.0

Te6edf3port Tff7b72= Ta5d6ff4242

Te6edf3network_name Tff7b72= Ta5d6ffprivate_ret

Te6edf3passphrase Tff7b72= Ta5d6ff2owjajquafIanPecAc

If you are hosting an entry-point on an operating system that does not support Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff``, you can use Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff`` instead, although it will not be as performant.

Tc9d1d9Connecting Reticulum Instances Over the Internet

Tc9d1d9================================================

Reticulum currently offers three interfaces suitable for connecting instances over the Internet: Te6edf3:ref:Te6edf3`Backbone<interfaces-backbone>`, Te6edf3:ref:Te6edf3`TCP<interfaces-tcps>` and Te6edf3:ref:Te6edf3`I2P<interfaces-i2p>`. Each interface offers a different set of features, and Reticulum users should carefully choose the interface which best suites their needs.

The Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff`` allows users to host an instance accessible over TCP/IP. This method is generally faster, lower latency, and more energy efficient than using Ta5d6ff``Ta5d6ffI2PInterfaceTa5d6ff``, however it also leaks more data about the server host.

The Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff`` is a very fast and efficient interface type available on POSIX operating systems, designed to handle thousands of connections simultaneously with low memory, processing and I/O overhead. It is fully compatible with the TCP-based interface types.

TCP connections reveal the IP address of both your instance and the server to anyone who can inspect the connection. Someone could use this information to determine your location or identity. Adversaries inspecting your packets may be able to record packet metadata like time of transmission and packet size. Even though Reticulum encrypts traffic, TCP does not, so an adversary may be able to use packet inspection to learn that a system is running Reticulum, and what other IP addresses connect to it. Hosting a publicly reachable instance over TCP also requires a publicly reachable IP address, which most Internet connections don't offer anymore.

The Ta5d6ff``Ta5d6ffI2PInterfaceTa5d6ff`` routes messages through the Ta5d6ff`Invisible Internet Protocol (I2P) Tffd700<https://geti2p.net/en/>Ta5d6ff`_. To use this interface, users must also run an I2P daemon in parallel to Ta5d6ff``Ta5d6ffrnsdTa5d6ff``. For always-on I2P nodes it is recommended to use Ta5d6ff`i2pd Tffd700<https://i2pd.website/>Ta5d6ff`_.

By default, I2P will encrypt and mix all traffic sent over the Internet, and hide both the sender and receiver Reticulum instance IP addresses. Running an I2P node will also relay other I2P user's encrypted packets, which will use extra bandwidth and compute power, but also makes timing attacks and other forms of deep-packet-inspection much more difficult.

I2P also allows users to host globally available Reticulum instances from non-public IP's and behind firewalls and NAT.

In general it is recommended to use an I2P node if you want to host a publicly accessible instance, while preserving anonymity. If you care more about performance, and a slightly easier setup, use TCP.

Tc9d1d9Adding Radio Interfaces

Tc9d1d9=======================

Once you have Reticulum installed and working, you can add radio interfaces with any compatible hardware you have available. Reticulum supports a wide range of radio hardware, and if you already have any available, it is very likely that it will work with Reticulum. For information on how to configure this, see the Te6edf3:ref:Te6edf3`Interfaces<interfaces-main>` section of this manual.

If you do not already have transceiver hardware available, you can easily and cheaply build an Te6edf3:ref:Te6edf3`RNode<rnode-main>`, which is a general-purpose long-range digital radio transceiver, that integrates easily with Reticulum.

To build one yourself requires installing a custom firmware on a supported LoRa development board with an auto-install script or web-based flasher. Please see the Te6edf3:ref:Te6edf3`Communications Hardware<hardware-main>` chapter for a guide. If you prefer purchasing a ready-made unit, you can refer to the Te6edf3:ref:Te6edf3`list of suppliers<rnode-suppliers>`.

Other radio-based hardware interfaces are being developed and made available by the broader Reticulum community. You can find more information on such topics over Reticulum-based information sharing systems.

If you have communications hardware that is not already supported by any of the Te6edf3:ref:Te6edf3`existing interface types<interfaces-main>`, it is easy to write (and potentially publish) a Te6edf3:ref:Te6edf3`custom interface module<interfaces-custom>` that makes it compatible with Reticulum.

Tc9d1d9Creating and Using Custom Interfaces

Tc9d1d9====================================

While Reticulum includes a flexible and broad range of built-in interfaces, these will not cover every conceivable type of communications hardware that Reticulum can potentially use to communicate.

It is therefore possible to easily write your own interface modules, that can be loaded at run-time and used on-par with any of the built-in interface types.

For more information on this subject, and code examples to build on, please see the Te6edf3:ref:Te6edf3`Configuring Interfaces<interfaces-main>` chapter.

Tc9d1d9Develop a Program with Reticulum

Tc9d1d9================================

If you want to develop programs that use Reticulum, the easiest way to get started is to install the latest release of Reticulum via pip:

Tb4b4b4.. Tff7b72codeTb4b4b4::

pip install rns

The above command will install Reticulum and dependencies, and you will be ready to import and use RNS in your own programs. The next step will most likely be to look at some Te6edf3:ref:Te6edf3`Example Programs<examples-main>`.

The entire Reticulum API is documented in the Te6edf3:ref:Te6edf3`API Reference<api-main>` chapter of this manual. Before diving in, it's probably a good idea to read this manual in full, but at least start with the Te6edf3:ref:Te6edf3`Understanding Reticulum<understanding-main>` chapter.

Tb4b4b4.. Tff7b72_install-guides:

Tc9d1d9Platform-Specific Install Notes

Tc9d1d9===============================

Some platforms require a slightly different installation procedure, or have various quirks that are worth being aware of. These are listed here.

Tc9d1d9Android

Tc9d1d9^^^^^^^

Reticulum can be used on Android in different ways. The easiest way to get started is using an app like Ta5d6ff`Sideband Tffd700<https://unsigned.io/sideband>Ta5d6ff`_.

For more control and features, you can use Reticulum and related programs via the Ta5d6ff`Termux app Tffd700<https://termux.com/>Ta5d6ff`_, at the time of writing available on Ta5d6ff`F-droid Tffd700<https://f-droid.org>Ta5d6ff`_.

Termux is a terminal emulator and Linux environment for Android based devices, which includes the ability to use many different programs and libraries, including Reticulum.

To use Reticulum within the Termux environment, you will need to install Ta5d6ff``Ta5d6ffpythonTa5d6ff`` and the Ta5d6ff``Ta5d6ffpython-cryptographyTa5d6ff`` library using Ta5d6ff``Ta5d6ffpkgTa5d6ff``, the package-manager build into Termux. After that, you can use Ta5d6ff``Ta5d6ffpipTa5d6ff`` to install Reticulum.

From within Termux, execute the following:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# First, make sure indexes and packages are up to date.

pkg update

pkg upgrade

T8b949e# Then install python and the cryptography library.

pkg install python python-cryptography

T8b949e# Make sure pip is up to date, and install the wheel module.

pip install wheel pip --upgrade

T8b949e# Install Reticulum

pip install rns

If for some reason the Ta5d6ff``Ta5d6ffpython-cryptographyTa5d6ff`` package is not available for your platform via the Termux package manager, you can attempt to build it locally on your device using the following command:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# First, make sure indexes and packages are up to date.

pkg update

pkg upgrade

T8b949e# Then install dependencies for the cryptography library.

pkg install python build-essential openssl libffi rust

T8b949e# Make sure pip is up to date, and install the wheel module.

pip install wheel pip --upgrade

T8b949e# To allow the installer to build the cryptography module,

T8b949e# we need to let it know what platform we are compiling for:

Tffa657export Te6edf3CARGO_BUILD_TARGETTff7b72=Ta5d6ff"aarch64-linux-android"

T8b949e# Start the install process for the cryptography module.

T8b949e# Depending on your device, this can take several minutes,

T8b949e# since the module must be compiled locally on your device.

pip install cryptography

T8b949e# If the above installation succeeds, you can now install

T8b949e# Reticulum and any related software

pip install rns

It is also possible to include Reticulum in apps compiled and distributed as Android APKs. A detailed tutorial and example source code will be included here at a later point. Until then you can use the Ta5d6ff`Sideband source code Tffd700<https://github.com/markqvist/sideband>Ta5d6ff`_ as an example and starting point.

Tc9d1d9ARM64

Tc9d1d9^^^^^

On some architectures, including ARM64, not all dependencies have precompiled binaries. On such systems, you may need to install Ta5d6ff``Ta5d6ffpython3-devTa5d6ff`` (or similar) before installing Reticulum or programs that depend on Reticulum.

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# Install Python and development packages

sudo apt update

sudo apt install python3 python3-pip python3-dev

T8b949e# Install Reticulum

python3 -m pip install rns

With these packages installed, Ta5d6ff``Ta5d6ffpipTa5d6ff`` will be able to build any missing dependencies

on your system locally.

Tc9d1d9Debian Bookworm

Tc9d1d9^^^^^^^^^^^^^^^

On versions of Debian released after April 2023, it is no longer possible by default to use Ta5d6ff``Ta5d6ffpipTa5d6ff`` to install packages onto your system. Unfortunately, you will need to use the replacement Ta5d6ff``Ta5d6ffpipxTa5d6ff`` command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# Install pipx

sudo apt install pipx

T8b949e# Make installed programs available on the command line

pipx ensurepath

T8b949e# Install Reticulum

pipx install rns

Alternatively, you can restore normal behaviour to Ta5d6ff``Ta5d6ffpipTa5d6ff`` by creating or editing the configuration file located at Ta5d6ff``Ta5d6ff~/.config/pip/pip.confTa5d6ff``, and adding the following section:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini

Tff7b72[global]

Te6edf3break-system-packages Tff7b72= Ta5d6fftrue

For a one-shot installation of Reticulum, without globally enabling the Ta5d6ff``Ta5d6ffbreak-system-packagesTa5d6ff`` option, you can use the following command:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

pip install rns --break-system-packages

Tb4b4b4.. Tff7b72noteTb4b4b4::

The Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.

Tc9d1d9MacOS

Tc9d1d9^^^^^

To install Reticulum on macOS, you will need to have Python and the Ta5d6ff``Ta5d6ffpipTa5d6ff`` package manager installed.

Systems running macOS can vary quite widely in whether or not Python is pre-installed, and if it is, which version is installed, and whether the Ta5d6ff``Ta5d6ffpipTa5d6ff`` package manager is also installed and set up. If in doubt, you can Ta5d6ff`download and install Tffd700<https://www.python.org/downloads/>Ta5d6ff`_ Python manually.

When Python and Ta5d6ff``Ta5d6ffpipTa5d6ff`` is available on your system, simply open a terminal window and use one of the following commands:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# Install Reticulum and utilities with pip:

pip3 install rns

T8b949e# On some versions, you may need to use the

T8b949e# flag --break-system-packages to install:

pip3 install rns --break-system-packages

Tb4b4b4.. Tff7b72noteTb4b4b4::

The Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.

Additionally, some version combinations of macOS and Python require you to manually add your installed Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages directory to your Te6edf3`PATH` environment variable, before you can use installed commands in your terminal. Usually, adding the following line to your shell init script (for example Ta5d6ff``Ta5d6ff~/.zshrcTa5d6ff``) will be enough:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

Tffa657export Te6edf3PATHTff7b72=Te6edf3$PATH:~/Library/Python/3.9/bin

Adjust Python version and shell init script location according to your system.

Tc9d1d9OpenWRT

Tc9d1d9^^^^^^^

On OpenWRT systems with sufficient storage and memory, you can install Reticulum and related utilities using the Te6edf3`opkg` package manager and Te6edf3`pip`.

Tb4b4b4.. Tff7b72noteTb4b4b4::

At the time of releasing this manual, work is underway to create pre-built Reticulum packages for OpenWRT, with full configuration, service and Ta5d6ff``Ta5d6ffuciTa5d6ff`` integration. Please see the Ta5d6ff`feed-reticulum Tffd700<https://github.com/gretel/feed-reticulum>Ta5d6ff`_ and Ta5d6ff`reticulum-openwrt Tffd700<https://github.com/gretel/reticulum-openwrt>Ta5d6ff`_ repositories for more information.

To install Reticulum on OpenWRT, first log into a command line session, and then use the following instructions:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# Install dependencies

opkg install python3 python3-pip python3-cryptography python3-pyserial

T8b949e# Install Reticulum

pip install rns

T8b949e# Start rnsd with debug logging enabled

rnsd -vvv

Tb4b4b4.. Tff7b72noteTb4b4b4::

The above instructions have been verified and tested on OpenWRT 21.02 only. It is likely that other versions may require slightly altered installation commands or package names. You will also need enough free space in your overlay FS, and enough free RAM to actually run Reticulum and any related programs and utilities.

Depending on your device configuration, you may need to adjust firewall rules for Reticulum connectivity to and from your device to work. Until proper packaging is ready, you will also need to manually create a service or startup script to automatically laucnh Reticulum at boot time.

Please also note that the Te6edf3`AutoInterface` requires link-local IPv6 addresses to be enabled for any Ethernet and WiFi devices you intend to use. If Ta5d6ff``Ta5d6ffip aTa5d6ff`` shows an address starting with Ta5d6ff``Ta5d6fffe80::Ta5d6ff`` for the device in question, Ta5d6ff``Ta5d6ffAutoInterfaceTa5d6ff`` should work for that device.

Tc9d1d9Raspberry Pi

Tc9d1d9^^^^^^^^^^^^

It is currently recommended to use a 64-bit version of the Raspberry Pi OS if you want to run Reticulum on Raspberry Pi computers, since 32-bit versions don't always have packages available for some dependencies. If Python and the Te6edf3`pip` package manager is not already installed, do that first, and then install Reticulum using Te6edf3`pip`.

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# Install dependencies

sudo apt install python3 python3-pip python3-cryptography python3-pyserial

T8b949e# Install Reticulum

pip install rns --break-system-packages

Tb4b4b4.. Tff7b72noteTb4b4b4::

The Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.

While it is possible to install and run Reticulum on 32-bit Rasperry Pi OSes, it will require manually configuring and installing required build dependencies, and is not detailed in this manual.

Tc9d1d9RISC-V

Tc9d1d9^^^^^^

On some architectures, including RISC-V, not all dependencies have precompiled binaries. On such systems, you may need to install Ta5d6ff``Ta5d6ffpython3-devTa5d6ff`` (or similar) before installing Reticulum or programs that depend on Reticulum.

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# Install Python and development packages

sudo apt update

sudo apt install python3 python3-pip python3-dev

T8b949e# Install Reticulum

python3 -m pip install rns

With these packages installed, Ta5d6ff``Ta5d6ffpipTa5d6ff`` will be able to build any missing dependencies on your system locally.

Tc9d1d9Ubuntu Lunar

Tc9d1d9^^^^^^^^^^^^

On versions of Ubuntu released after April 2023, it is no longer possible by default to use Ta5d6ff``Ta5d6ffpipTa5d6ff`` to install packages onto your system. Unfortunately, you will need to use the replacement Ta5d6ff``Ta5d6ffpipxTa5d6ff`` command instead, which places installed packages in an isolated environment. This should not negatively affect Reticulum, but will not work for including and using Reticulum in your own scripts and programs.

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

T8b949e# Install pipx

sudo apt install pipx

T8b949e# Make installed programs available on the command line

pipx ensurepath

T8b949e# Install Reticulum

pipx install rns

Alternatively, you can restore normal behaviour to Ta5d6ff``Ta5d6ffpipTa5d6ff`` by creating or editing the configuration file located at Ta5d6ff``Ta5d6ff~/.config/pip/pip.confTa5d6ff``, and adding the following section:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72text

[global]

break-system-packages = true

For a one-shot installation of Reticulum, without globally enabling the Ta5d6ff``Ta5d6ffbreak-system-packagesTa5d6ff`` option, you can use the following command:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72text

pip install rns --break-system-packages

Tb4b4b4.. Tff7b72noteTb4b4b4::

The Ta5d6ff``Ta5d6ff--break-system-packagesTa5d6ff`` directive is a somewhat misleading choice of words. Setting it will of course not break any system packages, but will simply allow installing Ta5d6ff``Ta5d6ffpipTa5d6ff`` packages user- and system-wide. While this *could* in rare cases lead to version conflicts, it does not generally pose any problems, especially not in the case of installing Reticulum.

Tc9d1d9Windows

Tc9d1d9^^^^^^^

On Windows operating systems, the easiest way to install Reticulum is by using the Ta5d6ff``Ta5d6ffpipTa5d6ff`` package manager from the command line (either the command prompt or Windows Powershell).

If you don't already have Python installed, Ta5d6ff`download and install Python Tffd700<https://www.python.org/downloads/>Ta5d6ff`_. At the time of publication of this manual, the recommended version is Ta5d6ff`Python 3.12.7 Tffd700<https://www.python.org/downloads/release/python-3127>Ta5d6ff`_.

**Important!** When asked by the installer, make sure to add the Python program to your PATH environment variables. If you don't do this, you will not be able to use the Ta5d6ff``Ta5d6ffpipTa5d6ff`` installer, or run the included Reticulum utility programs (such as Ta5d6ff``Ta5d6ffrnsdTa5d6ff`` and Ta5d6ff``Ta5d6ffrnstatusTa5d6ff``) from the command line.

After installing Python, open the command prompt or Windows Powershell, and type:

Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72shell

pip install rns

You can now use Reticulum and all included utility programs directly from your preferred command line interface.

Tc9d1d9Pure-Python Reticulum

Tc9d1d9=====================

Tb4b4b4.. Tff7b72warningTb4b4b4::

If you use the Ta5d6ff``Ta5d6ffrnspureTa5d6ff`` package to run Reticulum on systems that

do not support Ta5d6ff`PyCA/cryptography Tffd700<https://github.com/pyca/cryptography>Ta5d6ff`_, it is

important that you read and understand the Te6edf3:ref:Te6edf3`Cryptographic Primitives <understanding-primitives>`

section of this manual.

In some rare cases, and on more obscure system types, it is not possible to install one or more dependencies. In such situations, you can use the Ta5d6ff``Ta5d6ffrnspureTa5d6ff`` package instead of the Ta5d6ff``Ta5d6ffrnsTa5d6ff`` package, or use Ta5d6ff``Ta5d6ffpipTa5d6ff`` with the Ta5d6ff``Ta5d6ff--no-dependenciesTa5d6ff`` command-line option. The Ta5d6ff``Ta5d6ffrnspureTa5d6ff`` package requires no external dependencies for installation. Please note that the actual contents of the Ta5d6ff``Ta5d6ffrnsTa5d6ff`` and Ta5d6ff``Ta5d6ffrnspureTa5d6ff`` packages are *completely identical*. The only difference is that the Ta5d6ff``Ta5d6ffrnspureTa5d6ff`` package lists no dependencies required for installation.

No matter how Reticulum is installed and started, it will load external dependencies only if they are *needed* and *available*. If for example you want to use Reticulum on a system that cannot support Ta5d6ff``Ta5d6ffpyserialTa5d6ff``, it is perfectly possible to do so using the Te6edf3`rnspure` package, but Reticulum will not be able to use serial-based interfaces. All other available modules will still be loaded when needed.